home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_curl.idb / usr / freeware / catman / p_man / cat3 / libcurl-multi.Z / libcurl-multi
Text File  |  2002-07-08  |  5KB  |  106 lines
  1. libcurl-multi(5)     libcurl multi interface     libcurl-multi(5)
  2.  
  3.  
  4.  
  5. NNAAMMEE
  6.        libcurl-multi - how to use the multi interface
  7.  
  8. DDEESSCCRRIIPPTTIIOONN
  9.        This is an overview on how to use the libcurl multi inter
  10.        face in your C programs.    There are specific man pages  for
  11.        each function mentioned in here.    There's    also the libcurl-
  12.        the-guide document for a    complete tutorial to  programming
  13.        with  libcurl  and the _l_i_b_c_u_r_l_(_3_) man page for an overview
  14.        of the libcurl easy interface.
  15.  
  16.        All functions in    the multi  interface  are  prefixed  with
  17.        curl_multi.
  18.  
  19. PPLLEEAASSEE NNOOTTIICCEE
  20.        The  multi interface is a rather    new member of the libcurl
  21.        family. It has not yet been very    widely used. It    may still
  22.        be  a  few more bugs lurking in there than we are used to.
  23.        That said, it might also    just work in every aspect you try
  24.        it. Please report all bugs and oddities you see.
  25.  
  26. OOBBJJEECCTTIIVVEESS
  27.        The  multi interface introduces several new abilities that
  28.        the easy    interface refuses to offer. They are mainly:
  29.  
  30.        1. Enable a "pull" interface. The  application  that  uses
  31.        libcurl    decides    where and when to ask libcurl to get/send
  32.        data.
  33.  
  34.        2. Enable multiple  simultaneous     transfers  in    the  same
  35.        thread  without making it complicated for the application.
  36.  
  37.        3. Enable the application to  select()  on  its    own  file
  38.        descriptors  and    curl's file descriptors    simultaneous eas
  39.        ily.
  40.  
  41. OONNEE MMUULLTTII HHAANNDDLLEE MMAANNYY EEAASSYY HHAANNDDLLEESS
  42.        To use the multi    interface, you must first create a 'multi
  43.        handle'    with _c_u_r_l___m_u_l_t_i___i_n_i_t. This handle is then used as
  44.        input to    all further curl_multi_* functions.
  45.  
  46.        Each single transfer is built up    with an    easy handle.  You
  47.        must  create  them,  and    setup the appropriate options for
  48.        each easy handle, as outlined in    the _l_i_b_c_u_r_l_(_3_) man  page.
  49.  
  50.        When the    easy handle is setup for a transfer, then instead
  51.        of using    _c_u_r_l___e_a_s_y___p_e_r_f_o_r_m (as when using the easy  inter
  52.        face  for transfers), you should    instead    add the    easy han
  53.        dle to the multi     handle     using    _c_u_r_l___e_a_s_y___a_d_d___h_a_n_d_l.  The
  54.        multi  handle  is sometimes referred to as a multi stack
  55.        because of the fact that    it may hold  a    large  amount  of
  56.        easy handles.
  57.  
  58.        Should  you  change  your  mind,     the easy handle is again
  59.        removed from the    multi stack using  _c_u_r_l___m_u_l_t_i___r_e_m_o_v_e___h_a_n_
  60.        _d_l_e. Once removed from the multi    handle,    you can    again use
  61.        other easy interface functions like  curl_easy_perform  or
  62.        whatever    you think is necessary.
  63.  
  64.        Adding the easy handles to the multi handle does    not start
  65.        any transfer. Remember that one of  the    main  ideas  with
  66.        this interface is to let    your application drive.    You drive
  67.        the transfers by    invoking _c_u_r_l___m_u_l_t_i___p_e_r_f_o_r_m. libcurl will
  68.        then  transfer  data  if     there    is  anything available to
  69.        transfer. It'll use the callbacks and everything    else  you
  70.        have  setup in the individual easy handles. It'll transfer
  71.        data on all current transfers in    the multi stack    that  are
  72.        ready to    transfer anything. It may be all, it may be none.
  73.  
  74.        Your application    can acquire knowledge from  libcurl  when
  75.        it would    like to    get invoked to transfer    data, so that you
  76.        don't have to busy-loop and call     that  _c_u_r_l___m_u_l_t_i___p_e_r_f_o_r_m
  77.        like a mad man! _c_u_r_l___m_u_l_t_i___f_d_s_e_t    offers an interface using
  78.        which you can extract  fd_sets  from  libcurl  to  use  in
  79.        select()     or poll() calls in order to get to know when the
  80.        transfers in the    multi stack might  need     attention.  This
  81.        also makes it very easy for your    program    to wait    for input
  82.        on your own private file    descriptors at the same     time  or
  83.        perhaps    timeout    every now and then, should you want that.
  84.  
  85.        _c_u_r_l___m_u_l_t_i___p_e_r_f_o_r_m stores  the  number  of  still  running
  86.        transfers  in  one  of its input    arguments, and by reading
  87.        that you    can figure out when  all  the  transfers  in  the
  88.        multi  handles  are done. 'done'    does not mean successful.
  89.        One or more of the transfers may    have failed.
  90.  
  91.        To get information about    completed  transfers,  to  figure
  92.        out  success  or     not  and  similar,  _c_u_r_l___m_u_l_t_i___i_n_f_o___r_e_a_d
  93.        should be called. It can    return a message about a  current
  94.        or previous transfer. Repeated invokes of the function get
  95.        more messages until the message queue is    empty.
  96.  
  97.        When all    transfers in the multi stack  are  done,  cleanup
  98.        the  multi  handle with _c_u_r_l___m_u_l_t_i___c_l_e_a_n_u_p. Be careful and
  99.        please    note    that    you    MMUUSSTT    invoke     separate
  100.        _c_u_r_l___e_a_s_y___c_l_e_a_n_u_p  calls     on  every  single easy    handle to
  101.        clean them up properly.
  102.  
  103.  
  104.  
  105. libcurl    7.9.5          20 March 2001         libcurl-multi(5)
  106.